JSON Forms have two main components, a data schema and UI schema, that is the framework to build a customizable form-based web UI. In this guide, we introduce how to use JSON Forms in Itential Automation Platform (IAP) and provide a walk-through of how to navigate and use the Form Builder application.
Accessing JSON Forms
JSON forms currently are not part of any application. To access JSON forms, use the API route 'json-forms'.
For example: https://localhost:3443/json-forms
Home Page
The home page allows new forms to be created, existing forms to be deleted, and navigation to the Form Builder to update forms. All forms created are displayed in a card format, including previously created forms.
Modifying Forms
In Form Builder it is possible to change the structure and element composition of previously created forms. From this screen you can update a form name, add new form elements, change existing form elements, restructure a form through drag and drop reordering, and inspect different types of form previews.
General Navigation
There are two ways to navigate the application: sidebar and card menu.
Using the Sidebar
- From the sidebar, click any form in the list to navigate to the Form Builder for that particular form.
- The cards icon (upper-right corner) will navigate you to the Home page.
Using the Card Menu
- Click the stacked dots icon
to display more options inside of a card. - Click Preview to navigate directly to the preview tab for that form inside of Form Builder.
- Click Edit to navigate to the Form Builder page for editing.
Working with the JSON Form Builder
This section provides an overview of how to build and edit a JSON form.
Create a Form
To create a form:
- Go to the home page.
- Click the plus icon
to open Create New Form. - Enter a form name (required) and a description (optional).
- Click Save.
Edit a Form
To edit a form:
- Click the Edit menu option inside of the card. The Form Builder page opens.
- Inside of Form Builder, various actions can be performed which are described below.
Available Elements
The element bin is on the right side of the form builder. The form builder canvas is located in the middle.
Layout Elements
Used to structure a form and create logical groupings of form elements.
Form Elements
Used to add input fields to a form that will capture data.
Update the Form Name
The top bar of the form builder contains an input field that can be changed to update the form name.
Add Elements
Layout and form elements can be added to a form by dragging the available elements from the element bin onto the form canvas. For example, to add a text field to a form, drag-and-drop the element labeled Text Input.
Change Elements
Each form element can be expanded by clicking the arrow in the top right corner of its row. This will open the available properties for editing a form element. Below is a list of available properties currently supported for each form element.
| Element | Properties |
|---|---|
| Text Field | Label, Placeholder, Required |
| Number Field | Label, Placeholder, Required |
| Checkbox | Label |
| Property | Description |
|---|---|
| Label | The name of the field. |
| Placeholder | A user prompt or hint usually displayed inside of the input field before data is entered. |
| Required | Data entry is required. |
To update the label of a layout element, edit the text field next to the Container label.
Reorder Elements
- Any form element can be reordered by dragging it from its original location to a new location and dropping it.
Delete Elements
- Click the trash can button
(top-right corner) to delete an element from the form.
Save Form Changes
- Click the Save button to capture any changes made to a form.
Delete a Form
- From the home page, click the Delete menu option inside of the card to remove the form permanently.
Preview a Form
Form Element Preview
Form Builder has a convenient form element preview display to show you what the element will look like as you are editing its properties.
Rendering a Preview
To see a rendered version of a form:
- From the home view, click the Preview menu option inside the card.
- From the form builder view, click the Preview tab.
- A preview of the form will display as the end user will see it.
- Form validation and submission can also be tested from here.
JSON Schema and UI Schema Preview
To evaluate the underlying data structures that are generated as a form is built, click the JSON tab from the form builder view. The JSON schema displays.
